Worker channel configuration proxy (GET/PUT /api/v1/workers/{name}/channels...)

Summary

Connecting a worker to a messaging channel (QQ / Matrix / DingTalk / Feishu / WeChat / ...) has always required host access: SSH in, docker exec, hand-edit channels in the worker's agent.json, watch for the hot-reload log line. The worker's qwenpaw app port (8088) is not published to the host network, so no user — L1 admin or L2 team human — has any in-band path to this configuration.

The worker's qwenpaw app already exposes the complete channel-configuration HTTP API (/api/config/channels... — the same surface the QwenPaw console Channels page drives through the worker's own client; version-agnostic — verified byte-identical across the official QwenPaw 2.0.1 / 2.2.0 / 2.2.1 releases). This PR adds the Controller proxy in front of it, so channel onboarding becomes a graphical operation from the workbench plugin / dashboard: pick a worker, fill the form, save, verify with health — no SSH, no docker exec, no hand-edited agent.json.

GET  /api/v1/workers/{name}/channels                       all channel configs
GET  /api/v1/workers/{name}/channels/types                 channel name list
GET  /api/v1/workers/{name}/channels/schemas               per-channel form schemas (UI render driver)
GET  /api/v1/workers/{name}/channels/{channel}             single channel config
PUT  /api/v1/workers/{name}/channels/{channel}             update (body = full channel config)
GET  /api/v1/workers/{name}/channels/{channel}/health      channel health / connection state
GET  /api/v1/workers/{name}/channels/{channel}/qrcode      QR auth (wechat / dingtalk scan)
GET  /api/v1/workers/{name}/channels/{channel}/qrcode/status?token=
POST /api/v1/workers/{name}/channels/{channel}/restart     stop/start channel (no agent restart)

What's included

• agentteams-controller/internal/server/worker_channels.go (new) — 9 fixed-path endpoints, fixed forwarding to the worker's qwenpaw channel API under its real /api/config/channels... contract; {channel} charset-validated pre-dial; qrcode/status query restricted to a token-only whitelist; PUT body forwarded verbatim with empty-body 400 pre-dial.
• agentteams-controller/internal/server/http.go — route registration (adjacent block, no other routes touched).
• agentteams-controller/internal/server/worker_channels_test.go (new) — 21 handler tests, incl. a version-contract table test pinning all 9 forwarded upstream paths.
• docs/design/worker-channels-api.md — design contract (endpoint table, read-back semantics, role matrix).
• docs/usage/resource-management.md (+ docs/zh-cn/...) — "Worker channel configuration (proxy)" section with the role-permission matrix.

Data boundary

• Fixed-path forwarding only, never a generic reverse proxy — the attack surface stays bounded to the 9 documented qwenpaw endpoints, the same discipline as the checkpoint and approval worker proxies.
• PUT is the qwenpaw-authoritative write path: upstream validates the body against the channel's pydantic model, persists into agent.json and hot-reloads the channel — no worker restart. Upstream 400/404/409/422 pass through verbatim (the 404 doubles as the version gate for a qwenpaw build without the router). An empty body is rejected 400 before the dial — upstream would treat it as an empty config and wipe the saved channel.
• Read-back validation → X-AgentTeams-MinIO-Persisted header (true/false/skipped): after a 200, the Controller reads the MinIO baseline (agents/{name}/.../agent.json) up to 3× (2s apart) and canonical-JSON-compares the channel block against what was saved. The worker's push_loop remains the single writer of the baseline; the header only observes. This exists because manual local-only edits have left the MinIO baseline stale in production, and a subsequent rebuild's mirror_all then overwrote the live config with the old baseline — a real credential-loss incident. The header surfaces that gap in-band; the response body stays verbatim.
• Layered boundary: admin any worker; L2 humans own teams only (middleware team check, then handler re-check); team leaders are read-only — mutations 403 (the middleware's worker ActionUpdate policy is same-team for leaders, so the handler is the real enforcement point); cross-team and standalone-worker access hides as 404 (never 403) so the endpoint cannot be used to probe which workers exist or which team owns them.
• Credentials are not masked: scoped callers can only reach agents in their own teams, and the connect form needs the stored values to round-trip unchanged (a masked form cannot re-save without clobbering the secret). L1 sees all workers, consistent with its existing worker-management surface.
• Global (non-agent-scoped) upstream path: a worker container runs a single qwenpaw agent profile; without X-Agent-Id the app resolves the active agent from config — the worker's own agent. No header plumbing needed.
• Embedded mode only: worker addressing = effective container prefix + system-wins console port (default 8088), the same chain the container is created with. Kube mode → uniform 503 before any worker lookup (existence not probed).
• Audit log: every successful mutation logs worker, upstream path, caller (role-qualified) and the read-back outcome.

Version contract (version-agnostic; verified on 2.0.1 / 2.2.0 / 2.2.1)

• Forwarding prefix. Requests are forwarded to the worker's real config API path, /api/config/channels/... — the contract the worker's own client (qwenpaw_worker/api.py) and the integration coverage use. (The first revision forwarded without the /api prefix, which would have 404'd at runtime; fixed.)
• Verified across three official releases. The 9-route contract is byte-identical across the official QwenPaw 2.0.1 / 2.2.0 / 2.2.1 releases (hash-checked PyPI wheels). The proxy is pure path forwarding with no version-specific logic, so it works on any QwenPaw in the 2.0.1 → 2.2.1 range with no version pin required to merge or run it; on a build without the channel router, the upstream's own 404 is passed through verbatim (version gate).
• conflict-check is a 2.2.x-only route. It is absent from 2.0.x; the 2.2.0 and 2.2.1 channel routers are byte-identical and expose it. Rather than ship a dead endpoint on a 2.0.x pin, the proxy intentionally does not offer it yet; re-adding after a 2.2.x pin is a one-line table entry plus the existing handler shape — an independent small follow-up, not a dependency of this PR.
• Contract test. TestChannelsUpstreamPathsMatchWorkerContract pins all 9 forwarded upstream paths against the worker contract (expectations written from the worker client, not from this handler file), so any future worker API move fails the test instead of silently 404-ing.
• MinIO read-back timing. X-AgentTeams-MinIO-Persisted: false means "not yet converged within the bounded read-back window", not "write failed" — the 200 body is authoritative, and the header is advisory when the worker's push-loop interval exceeds the window.

Tests

• 21 handler tests (worker_channels_test.go): verbatim forwarding of list/types/schemas/single; PUT body forwarding + read-back true (canonicalization makes the comparison field-order-independent — asserted with a deliberately reordered baseline); read-back converging on the second attempt (simulated push_loop lag); missing baseline → false; no storage client → skipped; empty body 400 with zero dials; invalid channel names (../qq, QQ, a.b, x/y) → 400 with zero dials; cross-team 404 (no dial); same-team L2 read 200 and handler-level PUT 200; team-leader mutation 403 + read 200; kube mode 503 (no dial); unknown worker 404; standalone worker hidden from L2 humans / visible to admin; upstream 404 passthrough verbatim (version gate); upstream 500 → 502; restart method+path+body forwarding; version-contract table test pinning all 9 forwarded upstream paths to the worker's real /api/config/channels... contract (expectations written from qwenpaw_worker/api.py, independent of this handler's source); qrcode/status query whitelist (missing token 400, unknown param 400, valid token forwarded escaped).
• Full go test ./... on the main baseline: all green except one pre-existing environment failure in internal/executor (the test sandbox lacks the unzip binary; CI has it) — untouched by this diff. gofmt/go vet clean.

Related

• feat(controller): allow L2 humans to update worker skills within their teams #1212 — worker-scoped update policy (merged to main): the middleware dependency for the L2 write path — with it in main, the L2 write path (PUT/restart) is functional.
• feat(controller): add team-scoped worker tool approval endpoints for L2 humans #1216 — per-worker approval-level proxy: same pattern (worker addressing, W8 404 anti-probing, handler-enforced leader read-only); authorizer.go is untouched by this PR, so there is no shared-hunk conflict.
• Design: docs/design/worker-channels-api.md.

Worker 频道配置代理（GET/PUT /api/v1/workers/{name}/channels...）

摘要

Worker 接消息频道（QQ / Matrix / 钉钉 / 飞书 / 微信 …）此前必须宿主机操作：SSH → docker exec → 手改 agent.json 的 channels 段 → 盯热加载日志。Worker 的 qwenpaw app 端口（8088）未发布到宿主网络，L1 admin 和 L2 团队用户都没有带内配置路径。

Worker 的 qwenpaw app 已完整暴露频道配置 HTTP API（/api/config/channels...——Worker 自身客户端 qwenpaw_worker/api.py 与集成覆盖使用的真实契约；版本无关——官方 QwenPaw 2.0.1 / 2.2.0 / 2.2.1 三个 release 逐字一致（PyPI hash 核验））。本 PR 在其前加 Controller 代理，频道接入变成图形化操作（工作台插件 / dashboard）：选 worker、填表单、保存、health 验证——无 SSH、无 docker exec、无手改 agent.json。

包含内容

• agentteams-controller/internal/server/worker_channels.go（新）— 9 个固定路径端点，固定转发到 Worker qwenpaw 频道 API 的真实 /api/config/channels... 契约；{channel} 拨号前字符合入表校验；qrcode/status 查询仅允许 token 白名单；PUT body 原样转发、空 body 拨号前 400 拒。
• agentteams-controller/internal/server/http.go — 路由注册（相邻块，不动其他路由）。
• agentteams-controller/internal/server/worker_channels_test.go（新）— 21 个 handler 测试，含钉住全部 9 条转发上游路径的版本契约表测试。
• docs/design/worker-channels-api.md — 设计契约（端点表、读回语义、角色矩阵）。
• docs/usage/resource-management.md（+ zh-cn）—「Worker channel configuration (proxy)」节，含角色权限矩阵。

数据边界

• 仅固定路径转发，非通用反代——攻击面限定在 9 个已文档化端点，与 checkpoint/approval worker 代理同纪律。
• PUT = qwenpaw 官方写路径：上游按频道 pydantic 模型校验 body → 落 agent.json → 热加载免重启。上游 400/404/409/422 原样透传（404 兼作无此路由的 qwenpaw 构建的版本门）。空 body 拨号前 400 拒——上游会把空对象当配置抹掉已存频道。
• 读回校验 → X-AgentTeams-MinIO-Persisted 头（true/false/skipped）：200 后 Controller 读 MinIO 基线（至多 3 次、间隔 2s），canonical-JSON 比对频道块与已存值。push_loop 仍是基线唯一写者，该头只观测。动因：生产上手工只写本地曾使 MinIO 基线停旧，后续重建的 mirror_all 用旧基线覆盖了活配置——真实的凭据丢失事故。该头把这类缺口带内暴露；响应 body 保持原样。
• 分层边界：admin 全量；L2 人类仅本团队（middleware 团队检查 + handler 复检）；团队 Leader 只读——写操作 403（middleware 对 Leader 的 worker ActionUpdate 策略是同团队放行，handler 才是真强制点）；跨团队与独立 worker 一律 404（从不 403），端点不可用于探测 worker 存在性或所属团队。
• 凭据不脱敏：范围调用方只能到本团队 agent，且表单回写需要已存值（脱敏表单无法原样回存，会覆盖密钥）；L1 看全量，与其既有 worker 管理面一致。
• 全局（非 agent-scoped）上游路径：Worker 容器单 qwenpaw agent profile，无 X-Agent-Id 时 app 从配置解析活动 agent = worker 自身，无需 header 传递。
• 仅 embedded 模式：worker 寻址 = 生效容器前缀 + system-wins console 端口（默认 8088），与容器创建同一链路。kube 模式 → 任何 worker 查找前统一 503（不探测存在性）。
• 审计日志：每次成功变更记 worker、上游路径、调用方（带角色）、读回结果。

版本契约（版本无关；已核验 2.0.1 / 2.2.0 / 2.2.1）

• 转发前缀：请求转发到 Worker 真实配置 API 路径 /api/config/channels/...——Worker 自身客户端（qwenpaw_worker/api.py）与集成覆盖使用的契约。（首版转发漏了 /api 前缀，运行时会 404，已修正。）
• 三版官方 release 核验：9 路由契约在官方 QwenPaw 2.0.1 / 2.2.0 / 2.2.1 三个 release 中逐字一致（PyPI hash 核验的 wheel）。代理是纯路径转发、无任何版本逻辑，任意 2.0.1 → 2.2.1 的 QwenPaw 均可直接运行，无需 pin 特定版本即可合并；对无 channel router 的构建，上游自身 404 原样透传（版本门）。
• conflict-check 为 2.2.x 附加路由：2.0.x 无此路由（2.2.0/2.2.1 的 channel router 逐字一致且均暴露）。为避免在 2.0.x pin 上留死端点，本 PR 暂不代理；2.2.x pin 落地后一行表项 + 既有 handler 形状即可加回（独立小 follow-up，非本 PR 依赖）。
• 契约测试：TestChannelsUpstreamPathsMatchWorkerContract 把全部 9 条转发上游路径钉在 worker 契约上（期望值从 worker 客户端独立写出，不照抄本 handler 源码），worker API 将来移动会先让测试红，而不是运行时静默 404。
• MinIO 读回时序：X-AgentTeams-MinIO-Persisted: false = 「有界读回窗口内未收敛」而非「写失败」——200 body 是权威，worker push-loop 间隔超过窗口时该头为参考值。

测试

• 21 个 handler 用例（worker_channels_test.go）：list/types/schemas/single 原样透传；PUT body 转发 + 读回 true（canonical 化使比对与字段顺序无关——用刻意乱序基线断言）；读回第 二 次收敛（模拟 push_loop 滞后）；基线缺失 → false；无存储客户端 → skipped；空 body 400 零拨号；非法频道名（../qq、QQ、a.b、x/y）→ 400 零拨号；跨团队 404（不拨号）；同团队 L2 读 200 与 handler 级 PUT 200；团队 Leader 写 403 + 读 200；kube 模式 503（不拨号）；未知 worker 404；独立 worker 对 L2 隐藏 / 对 admin 可见；上游 404 原样透传（版本门）；上游 500 → 502；restart 方法+路径+body 转发；版本契约表测试钉住全部 9 条转发上游路径到 worker 真实 /api/config/channels... 契约（期望值从 qwenpaw_worker/api.py 独立写出）；qrcode/status 查询白名单（缺 token 400、未知参数 400、合法 token 转义后转发）。
• 全量 go test ./...（21 包）全绿，go build/go vet 干净。

相关

• feat(controller): allow L2 humans to update worker skills within their teams #1212 — worker-scoped update policy（已合入 main）：L2 写路径的 middleware 依赖——随其在 main，L2 写路径（PUT/restart）已可用。
• feat(controller): add team-scoped worker tool approval endpoints for L2 humans #1216 — worker 审批级别代理：同款模式（worker 寻址、W8 404 防探测、handler 强制 Leader 只读）；本 PR 不碰 authorizer.go，无共享 hunk 冲突。
• 设计文档：docs/design/worker-channels-api.md。